home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / Software / Servis / FFE / MOD.SWG / 0044_S3M 3.01.pas < prev    next >
Pascal/Delphi Source File  |  1997-03-02  |  18KB  |  371 lines
  1.           Scream Tracker 3.01 BETA File Formats And Mixing Info
  2.           =====================================================
  3.  
  4. This document finally containts the OFFICIAL information on s3m format and
  5. much more. There might be some errors though I've even checked this a few
  6. times, so if something seems weird, don't just blindly believe it but think
  7. first if it could be just a typo or something.
  8.  
  9.  
  10. -----------------------------------------------------------------------------
  11. What is the S3M file format?
  12. What is the samplefile format?
  13. What is the adlib instrument format?
  14.  
  15.  
  16.         The first table describes the S3M header. All other blocks are
  17.         pointer to by pointers, so in theory they could be anywhere in
  18.         the file. However, the practical standard order is:
  19.         - header
  20.         - instruments in order
  21.         - patterns in order
  22.         - samples in order
  23.  
  24.         Next the instrument header is described. It is stored to S3M
  25.         for each instrument and also saved to the start of all samples
  26.         saved from ST3. Same header is also used by Advance Digiplayer.
  27.  
  28.         The third part is the description of the packed pattern format.
  29.  
  30.  
  31.                                 S3M Module header
  32.           0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  33.         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
  34.   0000: │ Song name, max 28 chars (end with NUL (0))                    │
  35.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  36.   0010: │                                               │1Ah│Typ│ x │ x │
  37.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  38.   0020: │OrdNum │InsNum │PatNum │ Flags │ Cwt/v │  Ffv  │'S'│'C'│'R'│'M'│
  39.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  40.   0030: │g.v│i.s│i.t│m.v│ x │ x │ x │ x │ x │ x │ x │ x │ x │ x │Special│
  41.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  42.   0040: │Channel settings for 32 channels, 255=unused,+128=disabled     │
  43.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  44.   0050: │                                                               │
  45.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  46.   0060: │Orders; length=OrdNum (should be even)                         │
  47.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  48.   xxx1: │Parapointers to instruments; length=InsNum*2                   │
  49.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  50.   xxx2: │Parapointers to patterns; length=PatNum*2                      │
  51.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  52.         xxx1=70h+orders
  53.         xxx2=70h+orders+instruments*2
  54.  
  55.         Parapointers to file offset Y is (Y-Offset of file header)/16.
  56.         You could think of parapointers as segments relative to the
  57.         start of the S3M file.
  58.  
  59.         Type    = File type: 16=ST3 module
  60.         Ordnum  = Number of orders in file (should be even!)
  61.     Insnum    = Number of instruments in file
  62.     Patnum    = Number of patterns in file
  63.         Cwt/v   = Created with tracker / version: &0xfff=version, >>12=tracker
  64.                         ST3.00:0x1300
  65.                         ST3.01:0x1301
  66.     Ffv    = File format version;
  67.                         1=old version used long ago (samples signed)
  68.                         2=standard (samples unsigned)
  69.         Flags   =  [ These are old flags for Ffv1. Not supported in ST3.01
  70.                    |  +1:st2vibrato
  71.                    |  +2:st2tempo
  72.                    |  +4:amigaslides
  73.                    | +32:enable filter/sfx with sb
  74.                    ]
  75.                     +8: 0vol optimizations
  76.                           Automatically turn off looping notes whose volume
  77.                           is zero for >2 note rows.
  78.                    +16: amiga limits
  79.                           Disallow any notes that go beond the amiga hardware
  80.                           limits (like amiga does). This means that sliding
  81.                           up stops at B#5 etc. Also affects some minor amiga
  82.                           compatibility issues.
  83.                   +128: special custom data in file
  84.         Special = pointer to special custom data (not used by ST3.01)
  85.     g.v    = global volume (see next section)
  86.     m.v    = master volume (see next section) 7 lower bits
  87.                   bit 8: stereo(1) / mono(0)
  88.     i.s    = initial speed (command A)
  89.     i.t        = initial tempo (command T)
  90.  
  91.         Channel settings:
  92.           bit 8: channel enabled
  93.         bit 0-7: channel type
  94.                  0..7   : Left Sample Channel 1-8
  95.                  8..15  : Right Sample Channel 1-8
  96.                  16..31 : Adlib channels (9 melody + 5 drums)
  97.  
  98.         Global volume directly divides the volume numbers used. So
  99.         if the module has a note with volume 48 and master volume
  100.         is 32, the note will be played with volume 24. This affects
  101.         both Gravis & SoundBlasters.
  102.  
  103.         Master volume only affects the SoundBlaster. It controls
  104.         the amount of sample multiplication (see mixing section
  105.         of this doc). The bigger the value the bigger the output
  106.         volume (and thus quality) will be. However if the value
  107.         is too big, the mixer may have to clip the output to
  108.         fit the 8 bit output stream. The default value works
  109.         pretty well. Note that in stereo, the mastermul is
  110.         internally multiplied by 11/8 inside the player since
  111.         there is generally more room in the output stream.
  112.  
  113.         Order list lists the order in which to play the patterns. 255=--
  114.         is the end of tune mark and 254=++ is just a marker that is
  115.         skipped.
  116.  
  117.  
  118.  
  119.                         Digiplayer/ST3 samplefileformat
  120.           0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  121.         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
  122.   0000: │[T]│ Dos filename (12345678.ABC)                   │    MemSeg │
  123.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  124.   0010: │Length │HI:leng│LoopBeg│HI:LBeg│LoopEnd│HI:Lend│Vol│ x │[P]│[F]│
  125.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  126.   0020: │C2Spd  │HI:C2sp│ x │ x │ x │ x │Int:Gp │Int:512│Int:lastused   │
  127.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  128.   0030: │ Sample name, 28 characters max... (incl. NUL)                 │
  129.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  130.   0040: │ ...sample name...                             │'S'│'C'│'R'│'S'│
  131.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  132.   xxxx:    sampledata
  133.  
  134.         Length / LoopBegin / LoopEnd are all 32 bit parameters although
  135.         ST3 only support file sizes up to 64,000 bytes. Files bigger
  136.         than that are clipped to 64,000 bytes when loaded to ST3. NOTE
  137.         that LoopEnd points to one byte AFTER the end of the sample,
  138.         so LoopEnd=100 means that byte 99.9999 (fixed) is the last one
  139.         played.
  140.         C2Spd  = Herz for middle C. ST3 only uses lower 16 bits.
  141.         Vol    = Default volume 0..64
  142.         Memseg = Pointer to sampledata
  143.                  Inside a sample or S3M, MemSeg tells the parapointer to
  144.                  the actual sampledata. In files all 24 bits are used.
  145.                  In memory the value points to the actual sample segment
  146.                  or Fxxx if sample is in EMS under handle xxx. In memory
  147.                  the first memseg byte is overwritten with 0 to create
  148.                  the dos filename terminator nul.
  149.         Int:Gp = Internal: Address of sample in gravis memory /32
  150.                  (only used while module in memory)
  151.         Int:512= Internal: flags for soundblaster loop expansion
  152.                  (only used while module in memory)
  153.         Int:las= Internal: last used position (only works with sb)
  154.                  (only used while module in memory)
  155.         [T]ype   1=Sample, 2=adlib melody, 3+=adlib drum (see below for
  156.                  adlib structure)
  157.     [F]lags, +1=loop on
  158.          +2=stereo (after Length bytes for LEFT channel,
  159.                another Length bytes for RIGHT channel)
  160.                  +4=16-bit sample (intel LO-HI byteorder)
  161.                  (+2/+4 not supported by ST3.01)
  162.         [P]ack   0=unpacked, 1=DP30ADPCM packing (not used by ST3.01)
  163.  
  164.  
  165.  
  166.                               adlib instrument format
  167.           0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  168.         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
  169.   0000: │[T]│ Dos filename (12345678.123)                   │00h│00h│00h│
  170.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  171.   0010: │D00│D01│D02│D03│D04│D05│D06│D07│D08│D09│D0A│D0B│Vol│Dsk│ x │ x │
  172.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  173.   0020: │C2Spd  │HI:C2sp│ x │ x │ x │ x │ x │ x │ x │ x │ x │ x │ x │ x │
  174.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  175.   0030: │ Sample name, 28 characters max... (incl. NUL)                 │
  176.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  177.   0040: │ ...sample name...                             │'S'│'C'│'R'│'I'│
  178.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  179.  
  180.         [T]ype  = 2:amel 3:abd 4:asnare 5:atom 6:acym 7:ahihat
  181.         C2Spd   = 'Herz' for middle C. ST3 only uses lower 16 bits.
  182.                   Actually this is a modifier since there is no
  183.                   clear frequency for adlib instruments. It scales
  184.                   the note freq sent to adlib.
  185.         D00..D0B contains the adlib instrument specs packed like this:
  186.         modulator:                                              carrier:
  187.         D00=[freq.muliplier]+[?scale env.]*16+[?sustain]*32+    =D01
  188.                 [?pitch vib]*64+[?vol.vib]*128
  189.     D02=[63-volume]+[levelscale&1]*128+[l.s.&2]*64        =D03
  190.     D04=[attack]*16+[decay]                    =D05
  191.     D06=[15-sustain]*16+[release]                =D07
  192.     D08=[wave select]                    =D09
  193.     D0A=[modulation feedback]*2+[?additive synthesis]
  194.     D0B=unused
  195.  
  196.  
  197.  
  198.                           packed pattern format
  199.           0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  200.         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
  201.   0000: │Length │ packed data, see below...
  202.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  203.  
  204.         Length = length of packed pattern
  205.  
  206.         Unpacked pattern is always 32 channels by 64 rows. Below
  207.         is the unpacked format st uses for reference:
  208.           Unpacked Internal memoryformat for patterns (not used in files):
  209.           NOTE: each channel takes 320 bytes, rows for each channel are
  210.                 sequential, so one unpacked pattern takes 10K.
  211.           byte 0 - Note; hi=oct, lo=note, 255=empty note,
  212.                    254=key off (used with adlib, with samples stops smp)
  213.           byte 1 - Instrument      ;0=..
  214.           byte 2 - Volume          ;255=..
  215.           byte 3 - Special command ;255=..
  216.           byte 4 - Command info    ;
  217.  
  218.         Packed data consits of following entries:
  219.         BYTE:what  0=end of row
  220.                    &31=channel
  221.                    &32=follows;  BYTE:note, BYTE:instrument
  222.                    &64=follows;  BYTE:volume
  223.                    &128=follows; BYTE:command, BYTE:info
  224.  
  225.         So to unpack, first read one byte. If it's zero, this row is
  226.         done (64 rows in entire pattern). If nonzero, the channel
  227.         this entry belongs to is in BYTE AND 31. Then if bit 32
  228.         is set, read NOTE and INSTRUMENT (2 bytes). Then if bit
  229.         64 is set read VOLUME (1 byte). Then if bit 128 is set
  230.         read COMMAND and INFO (2 bytes).
  231.  
  232.         For information on commands / how st3 plays them, see the
  233.         manual.
  234.     
  235.  
  236. -----------------------------------------------------------------------------
  237. What is the Stmik300old format?
  238. What is the STIMPORT file format?
  239. What is the SIMPLEXFILE format?
  240.  
  241.         The old stmik 300 (never published because it has no
  242.         usable interface) want's that the samples in the module
  243.         are pre-extended for soundblaster. This means that
  244.         samples have an extra 512 bytes of loop after their
  245.         loopend (or silence if no loop). The save option for
  246.         old stmik does this extension. Otherwise the fileformat
  247.         is the same as for a normal S3M.
  248.  
  249.         STIMPORT file format is supposed to be an easy way of
  250.         imputting weird data to st3. That is, it should be
  251.         easy to convert something to STIMPORT format. The format
  252.         goes like this:
  253.  
  254.           0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
  255.         ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐
  256.   0000: │'S'│'T'│'I'│'M'│'P'│'O'│'R'│'T'│i.s│ x │ x │ x │ x │ x │ x │ x │
  257.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  258.   0010: │Notedata...
  259.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  260.   xxxx: │Instruments...
  261.         ├───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┼───┤
  262.  
  263.         There are no patterns or orders, just a continuos note stream
  264.         of following structures:
  265.           0    1    2    3    4
  266.         ┌────┬────┬────┬────┬────┐
  267.         │Chan│Note│Inst│Cmnd│Info│
  268.         └────┴────┴────┴────┴────┘
  269.         Chan is the channel number for the note. Value 0 stands
  270.         for next row. Value 255 stands for end of note stream.
  271.         Note/Inst/Cmnd/Info are like in the unpacked memory pattern
  272.         (see previous section)
  273.  
  274.         After the notedata there can be instruments (optional)
  275.         Every instrument consits of the following block:
  276.           0    1    2    3    4
  277.         ┌────┬────┬────┬────┬────┬────┬────┬────┬─────────────────
  278.         │Inst│Loop│LoopBeg  │LoopEnd  │Length   │ Sampledata...
  279.         └────┴────┴────┴────┴────┴────┴────┴────┴─────────────────
  280.         Inst = number of instrument to load (0=end of instruments)
  281.         Loop = 1=loop enabled
  282.         LoopBeg/LoopEnd/Length = guess
  283.         Sampledata = raw sampledata for Length bytes.
  284.  
  285.  
  286.         SIMPLEXFORMAT has been used for some adlib musics. Dunno
  287.         if it's useful to you, but the st3 saves it like this:
  288.  
  289.         First is stores the 32 first instruments (80 bytes each,
  290.         just like in a S3M). Then it stores the raw notedata
  291.         for the entire song. This means it goes through the
  292.         order list and saves all the patererns in that order
  293.         unpacked. The resulting file will be BIG. The idea
  294.         is that it should be fairly easy to convert to something
  295.         from this.
  296.  
  297.  
  298. -----------------------------------------------------------------------------
  299. What is C2SPD?
  300. How to calculate the note frequencies like ST3?
  301. How does ST3 mix depending on master volume?
  302.  
  303.  
  304.         Finetuning (C2SPD) is actually the frequency in herz for
  305.         the note C4. Why is it C2SPD? Well, originally in ST2
  306.         the middle note was C2 and the name stuck. Later in ST3
  307.         the middle note was raised to C4 for more octaves... So
  308.         actually C2SPD should be called C4SPD...
  309.  
  310.  
  311.         Table for note frequencies used by ST3:
  312.  
  313.       note:  C    C#   D    D#   E    F    F#   G    G#   A    A#   B
  314.     period: 1712,1616,1524,1440,1356,1280,1208,1140,1076,1016,0960,0907
  315.     
  316.     middle octave is 4.
  317.     
  318.              8363 * 16 * ( period(NOTE) >> octave(NOTE) )
  319.     note_st3period = --------------------------------------------
  320.               middle_c_finetunevalue(INSTRUMENT)
  321.              
  322.     note_amigaperiod = note_st3period / 4
  323.              
  324.     note_herz=14317056 / note_st3period
  325.  
  326.         Note that ST3 uses period values that are 4 times larger than the
  327.         amiga to allow for extra fine slides (which are 4 times finer
  328.         than normal fine slides).
  329.  
  330.  
  331.         How ST3 mixes:
  332.  
  333.         1) volumetable is created in the following way:
  334.  
  335.         > volumetable[volume][sampledata]=volume*(sampledata-128)/64;
  336.  
  337.         NOTE: sampledata in memory is unsigned in ST3, so the -128 in the
  338.               formula converts it so that the volumetable output is signed.
  339.  
  340.         2) postprocessing table is created with this pseudocode:
  341.  
  342.         > z=mastervol&127;
  343.         > if(z<0x10) z=0x10;
  344.         > c=2048*16/z;
  345.         > a=(2048-c)/2;
  346.         > b=a+c;
  347.         >                     { 0                , if x < a
  348.         > posttable[x+1024] = { (x-a)*256/(b-a)  , if a <= x < b
  349.         >                     { 255              , if x > b
  350.  
  351.         3) mixing the samples
  352.  
  353.         output=1024
  354.         for i=0 to number of channels
  355.                 output+=volumetable[volume*globalvolume/64][sampledata];
  356.         next
  357.         realoutput=posttable[output]
  358.  
  359.  
  360.         This is how the mixing is done in theory. In practice it's a bit
  361.         different for speed reasons, but the result is the same.
  362.  
  363.  
  364. -----------------------------------------------------------------------------
  365. That's it. If there are any more questions, that's too bad :-) If you have
  366. problems with the S3M format, try to contact somone who already supports
  367. it (there is quite a lot of support for the S3M already, so that shouldn't
  368. be too hard...) Good luck for reading / writing Scream Tracker files.
  369.  
  370.  
  371.